빌드 & 배포 가이드

이 가이드는 로컬(개발자), 개발 서버, 운영 서버에서의 빌드 및 배포 명령어를 다룹니다.

사전 준비사항

• Java 17
• Gradle 8.x
• Docker & Docker Compose
• Docker Buildx (멀티 아키텍처 빌드용)
• Docker Hub 계정 (현재 newsyhan으로 로그인됨)

1) 로컬 (개발자)

Docker 없이 앱 실행 (빠른 반복 개발)

# UnifiedService를 Gradle로 직접 실행
./gradlew :UnifiedService:bootRun

Fat JAR 빌드

./gradlew :UnifiedService:bootJar
# 출력: UnifiedService/build/libs/*.jar

Docker로 빌드 & 실행 (로컬 테스트)

# 이미지 빌드 (단일 아키텍처, 로컬)
docker build -t newsyhan/akc-b2c-unified-service:local -f UnifiedService/Dockerfile .

# 컨테이너 실행 (/uploads 볼륨 제공)
docker run --rm -p 8089:8089 \
  -e SPRING_PROFILES_ACTIVE=docker \
  -e DB_USERNAME=antsome -e DB_PASSWORD='Q1w2e3r4%^' \
  -v $(pwd)/uploads:/uploads \
  newsyhan/akc-b2c-unified-service:local

참고: 디버깅 시 로그는 콘솔로 확인하세요. 로컬 빌드에서는 호스트 로그 디렉토리를 생성하지 않아도 됩니다.

2) 개발 서버 (리소스 제약) - 권장 워크플로우

전략: 이미지를 로컬(또는 CI)에서 빌드하고 Docker Hub에 푸시한 후, 개발 서버에서 pull & 실행

빌드 & 푸시 (로컬)

# buildx builder 확인 및 생성
docker buildx create --use --name multiplatform-builder || true
docker buildx inspect --bootstrap

# 멀티 아키텍처 이미지 빌드 & 푸시
./build-and-push.sh

build-and-push.sh는 linux/amd64와 linux/arm64용으로 빌드하고 newsyhan/akc-b2c-unified-service:latest 및 타임스탬프 태그를 푸시합니다.

개발 서버에서 배포

# 개발 서버에서
cd /root/syhan/amano/akc-b2c
# 개발용 compose 사용 (로그용 tmpfs)
docker-compose -f docker-compose.unified.production.yml pull
docker-compose -f docker-compose.unified.production.yml up -d

# 상태 확인
docker-compose -f docker-compose.unified.production.yml ps
docker-compose -f docker-compose.unified.production.yml logs -f unified-service

참고:

• 개발용 compose는 /app/logs에 tmpfs를 사용하여 권한 문제를 회피하고 속도를 높입니다.
• tmpfs는 휘발성이므로 재시작 시 로그가 삭제됩니다. 개발/테스트 환경에만 사용하세요.

3) 운영 서버 (로그 영구 보관, 보안)

서버 준비 (최초 1회)

# 로그 디렉토리 생성 및 소유권 설정 (컨테이너 사용자 UID 1000 가정)
sudo mkdir -p /var/log/akc-b2c
sudo chown -R 1000:1000 /var/log/akc-b2c
sudo chmod 755 /var/log/akc-b2c

# 환경 변수 예제 복사 및 수정
cp .env.production.example .env.production
# .env.production을 실제 비밀번호 및 토큰으로 수정

배포

# Pull & 실행 (운영용 compose)
docker-compose -f docker-compose.unified.prod.yml --env-file .env.production pull
docker-compose -f docker-compose.unified.prod.yml --env-file .env.production up -d

# 상태 확인
docker-compose -f docker-compose.unified.prod.yml ps
# Health Check
curl http://localhost:8089/actuator/health
# 로그 확인 (호스트)
tail -f /var/log/akc-b2c/parking-service.log

참고:

• 비밀은 .env.production에 저장하고 git에 커밋하지 마세요.
• 디스크 용량 확보를 위해 호스트에서 logrotate를 설정하세요.
• DB/Redis 접근을 제한하기 위해 네트워크/방화벽 규칙을 고려하세요.

4) 롤백

새 이미지에 문제가 있는 경우 이전 이미지 태그를 사용하세요:

# 서버에서
docker pull newsyhan/akc-b2c-unified-service:20251021-<timestamp>
# compose 이미지 태그를 업데이트하거나 로컬에서 재태그
# 그런 다음 up -d로 이전 태그 실행

5) CI/CD (GitHub Actions 간단 예제)

.github/workflows/docker-build.yml을 생성하여 feature-parking에 병합 시 자동으로 빌드 및 푸시할 수 있습니다 (선택 사항; 필요시 템플릿 제공 가능).

6) 트러블슈팅

• 로그 작성 권한 거부 → 호스트 /var/log/akc-b2c가 존재하고 올바른 소유권(UID:GID 1000:1000, 컨테이너 사용자 spring)인지 확인
• data.sql 오류 → 운영 및 개발 환경에서 DB가 이미 초기화된 경우 spring.sql.init.mode: never로 설정
• 이미지 매니페스트 오류 → docker buildx를 사용하여 멀티 아키텍처 이미지 푸시

추가로 필요하시면:

• GitHub Actions 워크플로우 파일 생성
• logrotate 설정 스니펫 추가
• .env.production 샘플 (비밀은 커밋하지 않음)

생성된 파일: PROBLEMS_AND_IMPROVEMENTS.md, BUILD_GUIDE.md